想當一個 Good PHPer，不但要寫程式、寫註解還要寫 API 文件，想到要維護三個地方工程師就累了。
要是能從程式碼或註解產生文件就好了呢。

今天...又是...拿出我珍藏的...舊文

Swagger API 是一個 REST API 的編輯、視覺化、自動產生工具。
你可以透過 yaml 或 json 格式的方式來產生視覺化的 API 文件。

我們將透過這個工具以及註解，將 Laravel API 直接轉換成文件。

安裝

1.去 github 上找一個看起來簡單的 swagger api 套件來安裝

例如我這個範例使用 zircote/swagger-php

2.為你的 api functions 加 annotations

/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/fizzbuzz",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */
public function index (Request $num)
{
    $result = $this->testService->getFizzBuzz($num);
    return $result;
}

產生方法一

寫一個腳本，再手動上傳

1.run generator

php generateApi.php > myApi.yml

2.發布 API

把產生出來的 yaml 手動丟上 swagger hub（要註冊帳號，免費版有限制）

產生方法二

用 Swagger UI + api 產生一個 html